FSMA

Section: Miscellaneous Library Functions (3X)
Updated: 10 October 1992
Index Return to Main Contents

NAME

fsm_create, fsm_destroy, fsm_alloc, fsm_free, fsm_size - fixed size memory allocator

SYNOPSIS

#include "fsma.h"

fsma_h fsm_create( size, slots_per_chunk, flags )
unsigned size ;
unsigned slots_per_chunk ;
int flags ;

void fsm_destroy( handle )
fsma_h handle ;

char *fsm_alloc( handle )
fsma_h handle ;

void fsm_free( handle, ptr )
fsma_h handle ;
char *ptr ;

unsigned fsm_size( handle )
fsma_h handle ;

DESCRIPTION

The fixed-size memory allocator routines allocate and free memory in fixed-size quantities. The basic operation is as follows: first fsm_create() is called to create an allocator for objects that are size bytes big. It returns an allocator handle (whose type is fsma_h). Everytime fsm_alloc() is called with that handle as an argument, it will return a pointer to a memory block of size bytes. fsm_alloc() works by allocating big chunks of memory, breaking them into blocks of size bytes and then allocating from that pool of blocks.

fsm_create() creates a memory allocator for objects of size bytes. The second argument determines the size of the chunks that are allocated because it defines how many objects should fit in a chunk. If slots_per_chunk is 0, fsm_create() will use a default chunk size. The flags argument is formed by ORing one or more of the following constants:

FSM_RETURN_ERROR: determines the behavior of the particular allocator in case of a malloc() failure. When used, the call that failed will return a value that indicates failure (the default behavior is to terminate the process)
FSM_ZERO_ALLOC: will cause memory blocks returned from the specified allocator by fsm_alloc() to be zeroed.
FSM_ZERO_FREE: will cause memory blocks returned to the specified allocator by fsm_free() to be zeroed. (this will help catch references to an object after free'ing it).
FSM_ZERO_DESTROY: will cause all memory associated with the allocator to be zeroed when the allocator is destroyed.

The constant FSM_NOFLAGS can be used to specify no flags.

fsm_destroy() destroys an allocator and frees all memory allocated by it.

fsm_alloc() allocates a memory block from the specified allocator. The block will be properly aligned.

fsm_free() returns a block to the specified allocator.

fsm_size() returns the size of blocks that are handed out by the specified allocator.

RETURN VALUES

fsm_create() returns an allocator handle, or NULL if the request fails.

fsm_alloc() returns a pointer to a memory block of the appropriate size or NULL if the request fails.

NOTES

fsm_alloc(), fsm_free() and fsm_size() are macros, so the & operator cannot be applied to them (if that is needed, you can use the functions _fsm_alloc() and _fsm_free() that perform the same job as the macros).

This document was created by man2html, using the manual pages.
Time: 06:35:31 GMT, May 19, 2025